---
title: tags
description: The tags configuration reference
---

The `tags` configuration allows you to define custom labels that can be used to match and filter resources in your Terraform configuration. While the [`dirs`](/reference/configuration/dirs) key also supports tags, this documentation specifically focuses on the top-level `tags` key, which enables you to define tags based on dynamic criteria such as the destination branch of a pull request.

By leveraging the top-level `tags` key, you can create more granular and flexible workflows that adapt to the specific context of your pull requests and branches.

## Default Configuration
```yaml
tags: {}
```

## Keys
| Key | Type | Description | 
| --- | --- | --- | 
| dest_branch | Map | Defines tags for destination branches with associated regular expressions that match branch names. | 

## Example Configuration


```yaml
tags:
  dest_branch:
    main: '^main$'
    staging: '^staging$'
    dev: '^dev$'
dirs:
  dev:
    tags: [dev]
  staging:
    tags: [staging]
  prod:
    tags: [prod]
```
In this example, the `tags` section defines a tag called `dest_branch`, which has three possible values: `main`, `staging`, and `dev`. Each value is associated with a regular expression that matches the corresponding branch name.The `dirs` section defines static tags for specific directories in your repository.
### Tag Definition
Each tag in the top-level `tags` configuration is defined as a key-value pair. The key represents the tag name, and the value is a map of tag values and their corresponding regular expressions.
## Using Tags in Tag Queries
Once tags are defined in the top-level `tags` configuration, you can use them in tag queries to match and filter resources based on specific criteria. Tag queries are used in various parts of the Terrateam configuration, such as workflows and access control.
### Example Workflow Configuration


```yaml
workflows:
  - tag_query: 'dest_branch:main'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: apply
```
In this example, the workflow is triggered when the `dest_branch` tag matches the `main` value. The `tag_query` field specifies the condition that must be met for the workflow to be executed.You can also combine tags from the top-level `tags` configuration with tags defined in the `dirs` section to create more specific and targeted workflows.
### Matching Tags with Regular Expressions
Terrateam uses regular expressions to match tags against the defined values in the top-level `tags` configuration. This allows for flexible and powerful matching capabilities.
In the example configuration, the regular expressions are defined as follows:
 
- `'^main`: Matches the exact string `main`.
- `'^staging`: Matches the exact string `staging`.
- `'^dev`: Matches the exact string `dev`.

You can customize the regular expressions to match your specific branch naming conventions or other criteria.

## Considerations
When configuring tags in the top-level `tags` section of the Terrateam configuration, keep the following considerations in mind: 
- Tags defined in the top-level `tags` section are dynamic and can be used to match resources based on the context of your pull requests, such as the destination branch.
- Tags defined in the `dirs` section are static and are assigned directly to specific directories in your repository.
- You can use tags from both the top-level `tags` configuration and the `dirs` section in combination to create more targeted and flexible workflows.
